.TH SG_LOGS "8" "May 2023" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_logs \- access log pages with SCSI LOG SENSE command
.SH SYNOPSIS
.B sg_logs
[\fI\-\-ALL\fR] [\fI\-\-all\fR] [\fI\-\-brief\fR] [\fI\-\-exclude\fR]
[\fI\-\-filter=FL\fR] [\fI\-\-full\fR] [\fI\-\-hex\fR] [\fI\-\-json[=JO]\fR]
[\fI\-\-js\-file=JFN\fR] [\fI\-\-list\fR] [\fI\-\-maxlen=LEN\fR]
[\fI\-\-name\fR] [\fI\-\-no_inq\fR] [\fI\-\-page=PG\fR] [\fI\-\-paramp=PP\fR]
[\fI\-\-pcb\fR] [\fI\-\-ppc\fR] [\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR]
[\fI\-\-readonly\fR] [\fI\-\-sp\fR] [\fI\-\-temperature\fR]
[\fI\-\-transport\fR] [\fI\-\-undefined\fR] [\fI\-\-vendor=VP\fR]
[\fI\-\-verbose\fR] \fIDEVICE\fR
.PP
.B sg_logs
\fI\-\-inhex=FN\fR  [\fI\-\-ALL\fR] [\fI\-\-all\fR] [\fI\-\-brief\fR]
[\fI\-\-exclude\fR] [\fI\-\-filter=FL\fR] [\fI\-\-full\fR] [\fI\-\-hex\fR]
[\fI\-\-json[=JO]\fR] [\fI\-\-js\-file=JFN\fR] [\fI\-\-list\fR]
[\fI\-\-name\fR] [\fI\-\-page=PG\fR] [\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR]
[\fI\-\-undefined\fR] [\fI\-\-vendor=VP\fR]
.PP
.B sg_logs
\fI\-\-select\fR  [\fI\-\-control=PC\fR] [\fI\-\-page=PG\fR] [\fI\-\-raw\fR]
[\fI\-\-reset\fR] [\fI\-\-sp\fR] [\fI\-\-verbose\fR] \fIDEVICE\fR
.PP
.B sg_logs
\fI\-\-enumerate\fR  [\fI\-\-filter=FL\fR] [\fI\-\-help\fR]
[\fI\-\-vendor=VP\fR] [\fI\-\-version\fR]
.PP
.B sg_logs
[\fI\-a\fR] [\fI\-A\fR] [\fI\-b\fR] [\fI\-c=PC\fR] [\fI\-D=DT\fR] [\fI\-e\fR]
[\fI\-E\fR] [\fI\-f=FL\fR] [\fI\-F\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-i=FN\fR]
[\fI\-l\fR] [\fI\-L\fR] [\fI\-m=LEN\fR] [\fI\-M=VP\fR] [\fI\-n\fR]
[\fI\-p=PG\fR] [\fI\-paramp=PP\fR] [\fI\-pcb\fR] [\fI\-ppc\fR] [\fI\-r\fR]
[\fI\-R\fR] [\fI\-select\fR] [\fI\-sp\fR] [\fI\-t\fR] [\fI\-T\fR] [\fI\-u\fR]
[\fI\-v\fR] [\fI\-V\fR] [\fI\-?\fR] [\fI\-x\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
This utility sends a SCSI LOG SENSE command to the \fIDEVICE\fR and then
outputs the response. The LOG SENSE command is used to fetch log pages which,
if known, are decoded by default. When the \fI\-\-reset\fR and/or
\fI\-\-select\fR option is given then a SCSI LOG SELECT command is issued
to the \fIDEVICE\fR. Alternatively one or more log page responses can be in
a file read using the \fI\-\-inhex=FN\fR option; in this case those responses
are decoded and the \fIDEVICE\fR argument, if given, is ignored.
.PP
In SPC\-4 revision 5 the subpage code was introduced to both the LOG SENSE and
LOG SELECT command. At the same time a page code field was introduced to the
to the LOG SELECT command. The log subpage code can range from 0 to 255 (0xff)
inclusive. The subpage code value 255 can be thought of as a wildcard.
.PP
The SYNOPSIS section above is divided into five forms. The first form
shows the options that can be used to send a LOG SENSE command to the
\fIDEVICE\fR and decode its response. The second form fetches data from a
file (named \fIFN\fR) and decodes it as if it were a response from a LOG
SENSE command. The third form shows the options that can be used to send a
LOG SELECT command. The fourth form groups various management options.
The last form shows the older, deprecated command line interface which is
maintained for backward compatibility.
.PP
When no options are given, just a \fIDEVICE\fR, that is equivalent to calling
this utility with the \fI\-\-list\fR option. In that case the names of the
supported log pages (but not subpages) are listed out.
.SH OPTIONS
Arguments to long options are mandatory for short options as well. The options
are arranged in alphabetical order based on the long option name.
.TP
\fB\-A\fR, \fB\-\-ALL\fR
fetch and decode all the log pages and subpages supported by the \fIDEVICE\fR.
This requires a two stage process: first the "supported log pages and
subpages" log page is fetched, then for each entry in its response, the
corresponding log page (or subpage) is fetched and displayed. Note that there
are many SCSI devices that do not support LOG SENSE subpages and respond
to this option with an illegal request sense key. In this case this utility
continues by fetching the supported log pages log page instead. In other
words if the \fI\-\-ALL\fR option fails then the \fI\-\-all\fR is used
instead. The reason is that almost certainly the \fIDEVICE\fR does not have
any log subpages to report.
.br
To force an error if the fetch of the supported log pages and subpages log
page fails use both the \fI\-\-ALL\fR and \fI\-\-full\fR options.
.br
Since some vendors don't list all log pages in the "supported log pages and
subpages" log page, the '\-lll' option can be given in addition. This will
merge both "supported ..." log pages then, from that resultant merged list,
fetch page contents.
.br
This option overrides the \fI\-\-page=PG\fR if the latter is also given.
.TP
\fB\-a\fR, \fB\-\-all\fR
outputs all the log pages supported by the \fIDEVICE\fR. This requires a two
stage process: first the "supported log pages" log page is fetched, then for
each entry in its response, the corresponding log page is fetched and
displayed. When used twice (e.g. '\-aa') all log pages and subpages are
fetched.
.br
This option overrides the \fI\-\-page=PG\fR if the latter is also given.
.TP
\fB\-b\fR, \fB\-\-brief\fR
shorten the amount of output for some log pages. For example the Tape
Alert log page only outputs parameters whose flags are set when
\fI\-\-brief\fR is given.
.TP
\fB\-c\fR, \fB\-\-control\fR=\fIPC\fR
accepts 0, 1, 2 or 3 for the \fIPC\fR argument:
    \fB0\fR : current threshold values
    \fB1\fR : current cumulative values
    \fB2\fR : default threshold values
    \fB3\fR : default cumulative values
.br
The default value is 1 (i.e. current cumulative values).
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
this option is used to output information held in this utility's internal
tables about known log pages including their name, acronym and fields. If
given, the \fIDEVICE\fR argument is ignored. When given once (e.g. '\-e')
all known pages are listed, sorted in ascending alphabetical acronym order.
.br
When given twice, vendor pages are excluded.  When given three times, all
known pages are listed, sorted in ascending numeric order listed; when given
four times, vendor pages are excluded from the numeric order.
.br
The \fI\-\-filter=FL\fR and \fI\-\-verbose\fR options reduce the output
of the enumeration.
.TP
\fB\-E\fR, \fB\-\-exclude\fR
this option excludes vendor specific pages and parameters from the output.
Trying to decode vendor specific pages and parameters does not necessarily
work well for many reasons. This option limits the output to pages and
parameters defined by T10.
.br
Only parameter fields identified in the drafts as 'vendor specific' are
excluded. So parameters codes identified as 'reserved' are shown.
.TP
\fB\-f\fR, \fB\-\-filter\fR=\fIFL\fR
\fIFL\fR is either a parameter code when \fIDEVICE\fR is given, or a
peripheral device type (pdt) (or other) if \fI\-\-enumerate\fR is given.
.br
In the parameter code case \fIFL\fR is a value between 0 and 65535 (0xffff)
and only the parameter section matching that code is output. If the
\fB\-\-hex\fR option is given the log parameter is output in hexadecimal
rather than decoding it. If the \fB\-\-hex\fR option is used twice then the
leading address on each line of hex is removed. If the \fB\-\-raw\fR option
is given then the log parameter is output in binary. Most log pages contain
one or more log parameters. Examples of those that don't follow that
convention are those pages that list supported log pages (and subpages).
.br
In the \fI\-\-enumerate\fR case, when \fIFL\fR >= zero it is taken as a
pdt value and only log pages associated with that pdt plus generic pages
listed in SPC are enumerated. If \fIFL\fR is \-1 then the filter does
nothing which is the same as not giving this option; when \fIFL\fR is \-2
then only generic pages listed in SPC are enumerated. If \fIFL\fR is \-10
then only generic direct access like (e.g. disk) pages are enumerated. If
\fIFL\fR is \-11 then only generic tape like pages (e.g. includes ADC)
are enumerated.
.TP
\fB\-F\fR, \fB\-\-full\fR
this option is only used in two situations: with the Application client (AC)
log page and with the \fI\-\-ALL\fR option. Typically the AC log page has
more than 16,000 bytes of user supplied data. Rather than print it all out,
the default is to print out the first 64 bytes of data. When this option is
given, the application client log pages is fully decoded.
.br
When both this option and the \fI\-\-ALL\fR option are given, then this
utility will exit with an error if the Supported log pages and subpages
log page is not available.
.TP
\fB\-h\fR, \fB\-\-help\fR
print out the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
The default action is to decode known log page numbers (and subpage numbers)
into text. When this option is used once, the response is output in
hexadecimal. When used twice, each line of hex has the ASCII equivalent shown
to the right. When used three times, the hex has no leading address nor
trailing ASCII making it suitable to be placed in a file (or piped). That
file might later be used by another invocation using the \fI\-\-inhex=FN\fR
option.
.br
A weaker form of this option, called \fI\-\-undefined\fR, handles the
formatting of hexadecimal output for fields that this utility is unable to
decode.
.TP
\fB\-i\fR, \fB\-\-in\fR=\fIFN\fR
Same as \fI\-\-inhex=FN\fR option. Kept for backward compatibility.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
This option may be used in two different contexts. One is with the
\fI\-\-select\fR to send a LOG SELECT command to the given \fIDEVICE\fR;
see the LOG SELECT section below.
.br
The other context is with no \fIDEVICE\fR argument given in which case
the contents of \fIFN\fR are decoded as if it were the response of a LOG
SENSE command (i.e. one or more log page). For decoding, the page and
subpage numbers are taken from \fIFN\fR while the peripheral device type
is either generic (i.e. from SPC) or the value given by \fI\-\-pdt=DT\fR.
.br
\fIFN\fR is treated as a file name (or '\-' for stdin) which contains ASCII
hexadecimal or binary representing a log page. The hexadecimal should be
arranged as 1 or 2 digits representing a byte each of which is whitespace or
comma separated. Anything from and including a hash mark to the end of line
is ignored. If the \fI\-\-raw\fR option is also given then \fIFN\fR is
treated as binary.
.TP
\fB\-j\fR[=\fIJO\fR], \fB\-\-json\fR[=\fIJO\fR]
output is in JSON format instead of plain text form. Note that arguments
to the short and long form are themselves optional and if present start
with "=" and no whitespace is permitted around that "=".
.br
See sg3_utils_json manpage or use '?' for \fIJO\fR to get a summary.
.TP
\fB\-J\fR, \fB\-\-js\-file\fR=\fIJFN\fR
output is in JSON format and it is sent to a file named \fIJFN\fR. If that
file exists then it is truncated. By default, the JSON output is sent to
stdout.
.br
When this option is given, the \fI\-\-json[=JO]\fR option is implied and
need not be given. The \fI\-\-json[=JO]\fR option may still be needed to
set the \fIJO\fR parameter to non-default values.
.TP
\fB\-l\fR, \fB\-\-list\fR
lists the names of the logs sense pages supported by this device. This is
done by reading the "supported log pages" log page. When used once only
log pages, but not subpages, are listed. When used twice the "supported
log pages and subpages" log page is output. Some vendors do not list some
log pages (e.g. those without any subpages) in the "supported log pages
and subpages" log page. To get a full inventory, this option can be used
three times (e.g. '\-lll') and the output of the two log pages is merged.
Even if the "supported log pages and subpages" log page is not supported
using this option three times will yield a list from the "supported log
pages" log page. In the absence of other options, the page/subpage names,
but not their contents, are shown when this option is given.
.br
The '\-lll' form may be useful with the \fI\-\-ALL\fR option to show the
contents of all pages referred to in either the "supported log page" or
the "supported log page and subpage" log pages.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
sets the "allocation length" field in the LOG SENSE cdb. The is the maximum
length in bytes that the response will be. Without this option (or \fILEN\fR
equal to 0) this utility first fetches the 4 byte response then does a second
access with the length indicated in the first (4 byte) response. Negative
values and 1 for \fILEN\fR are not accepted. Responses can be quite
large (e.g. the background scan results log page) and this option can be used
to limit the amount of information returned.
.br
The default \fILEN\fR is 65532 unless the \fI\-\-in=FN\fR option is given;
in that case the default is 262144 .
.TP
\fB\-n\fR, \fB\-\-name\fR
decode some log pages into 'name=value' entries, one per line. The name
contains no space and may be abbreviated and the value is decimal unless
prefixed by '0x'. Nesting is indicated by leading spaces. This form
is meant to be relatively easy to parse.
.br
This option is superseded by the \fI\-\-json[=JO]\fR option. If both are
given then this option is ignored.
.TP
\fB\-x\fR, \fB\-\-no_inq\fR
suppresses the output of information obtained from an initial call to the
INQUIRY command for the standard response. The default (assuming some other
options that suppress this output are also not given) is to output several
device identification strings.
.br
If this option is given twice (or more) then no INQUIRY command is sent
hence there will be no device identification string output either. Also the
peripheral device type (PDT) field will not be obtained so this utility will
not be able to differentiate between some log pages that are device
dependent. The utility will assume a PDT of 0 (i.e. a disk) unless the
\fI\-\-pdt=DT\fR option is given.
.TP
\fB\-O\fR, \fB\-\-old\fR
Switch to older style options. Please use as first option.
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR
log page name/number to access. \fIPG\fR is either an acronym, a page number,
or a page, subpage number pair. Available acronyms can be listed with the
\fI\-\-enumerate\fR option. Page (0 to 63) and subpage (0 to 255) numbers
are comma separated. They are decimal unless a hexadecimal indication is
given. A hexadecimal number can be specified by a leading "0x" or a
trailing "h".
.br
A few acronyms specify a range of subpage values in which case the acronym
may be followed by a comma then a subpage number. This method can also be
used to fetch the Supported subpages log page (e.g. \-\-page=temp,0xff).
.TP
\fB\-P\fR, \fB\-\-paramp\fR=\fIPP\fR
\fIPP\fR is the parameter pointer value to place in a field of that name in
the LOG SENSE cdb. A number in the range 0 to 65535 (0x0 to 0xffff) is
expected. When a value greater than 0 is given the \fI\-\-ppc\fR option
should be selected. The default value is 0.
.br
For log pages that have parameter codes, the \fIDEVICE\fR should return
only parameters code equal to \fIPP\fR or higher in its response.
.TP
\fB\-q\fR, \fB\-\-pcb\fR
show Parameter Control Byte settings (only relevant when log parameters
being output in ASCII). This byte includes the DU and TSD bits plus
the 'Format and linking' field (2 bits wide).
.TP
\fB\-D\fR, \fB\-\-pdt\fR=\fIDT\fR
\fIDT\fR is the peripheral device type (PDT) that is used when it is not
available from the \fIDEVICE\fR. There are several cases: when the
\fIDEVICE\fR is not given (e.g. when the \fI\-\-inhex=FN\fR or
\fI\-\-enumerate\fR option is given) and when \fIDEVICE\fR is and is
coupled with the \fI\-\-no_inq\fR option. That stops this utility
sending the SCSI INQUIRY command which is where this utility usually
finds the PDT associated log pages being decoded.
.br
Numerical values between -1 and 31 (inclusive) may be used where -1 implies
what is in SPC. SCSI Primary Commands (SPC) are common to all SCSI devices.
Names like 'tape', 'disk' and 'processor' may also be given for \fIDT\fR.
The default is 0 or 'disk' for SBC (and the associated standard acronym
may also be given which is 'sbc' in this case).
.TP
\fB\-Q\fR, \fB\-\-ppc\fR
sets the Parameter Pointer Control (PPC) bit in the LOG SENSE cdb. Default
is 0 (i.e. cleared). This bit was made obsolete in SPC\-4 revision 18.
.TP
\fB\-r\fR, \fB\-\-raw\fR
output the response in binary to stdout. Error messages and warnings are
output to stderr.
.br
This option may also be given together with \fI\-\-in=FN\fR in which case
the contents of \fIFN\fR are interpreted as binary data (and the response is
decoded as normal, not dumped as binary).
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag). The
default action is to try and open \fIDEVICE\fR read\-write then if that
fails try to open again with read\-only. However when a read\-write open
succeeds there may still be unwanted actions on the close (e.g. some OSes
try to do a SYNCHRONIZE CACHE command). So this option forces a read\-only
open on \fIDEVICE\fR and if it fails, this utility will exit. Note that
options like \fI\-\-select\fR most likely need a read\-write open.
.TP
\fB\-R\fR, \fB\-\-reset\fR
use SCSI LOG SELECT command (with the PCR bit set) to reset the all log
pages (or the given page). Exactly what is reset depends on the accompanying
SP bit (i.e. \fI\-\-sp\fR option which defaults to 0) and the
\fIPC\fR ("page control") value (which defaults to 1). Supplying this option
implies the \fI\-\-select\fR option as well. This option seems to clear error
counter log pages but leaves pages like self\-test results, start\-stop cycle
counter and temperature log pages unaffected. This option may be required to
clear log pages if a counter reaches its maximum value since the log page in
which the counter is found will remain "stuck" at its maximum value until
some user interaction (e.g. calling sg_logs with this option).
.TP
\fB\-S\fR, \fB\-\-select\fR
use a LOG SELECT command. The default action (i.e. when neither this option
nor \fI\-\-reset\fR is given) is to do a LOG SENSE command. See the LOG
SELECT section.
.TP
\fB\-s\fR, \fB\-\-sp\fR
sets the Saving Parameters (SP) bit. Default is 0 (i.e. cleared). When set
this instructs the device to store the current log page parameters (as
indicated by the DS and TSD parameter codes) in some non\-volatile location.
Hence the log parameters will be preserved across power cycles. This option
is typically not needed, especially if the GLTSD flag is clear in the
control mode page which causes the \fIDEVICE\fR to periodically save all
saveable log parameters to non\-volatile storage.
.TP
\fB\-t\fR, \fB\-\-temperature\fR
outputs the temperature. First looks in the temperature log page and if
that is not available tries the Informational Exceptions log page which
may also have the current temperature (especially on older disks).
.TP
\fB\-T\fR, \fB\-\-transport\fR
outputs the transport ('Protocol specific port') log page. Equivalent to
setting '\-\-page=18h'.
.TP
\fB\-u\fR, \fB\-\-undefined\fR
to see fields decoded, the \fI\-\-hex\fR option cannot be used. However some
fields are not defined in the T10 documents and in that case they are output
in hex. This option controls the format of 'undefined' fields when they
output in hex. Multiple uses of this option has the same sense as the
\fI\-\-hex\fR option. For example '\-uu' will output undefined fields in
hexadecimal with an ASCII rendering to the right of each line.
.TP
\fB\-M\fR, \fB\-\-vendor\fR=\fIVP\fR
where \fIVP\fR is a vendor/manufacturer (e.g. "sea" for Seagate) or
product (group) acronym (e.g. "lto5" for the 5th generation LTO (tape)
consortium). Either the whole log page is vendor specific (e.g. page
numbers 0x30 to 0x3f) or part of a T10 defined log page is vendor specific.
For example SPC\-5 defines parameter code 0x0 of page 0x2f (the Informational
Exceptions log page) and states that the remaining parameter codes (i.e. 0x1
to 0xffff) are vendor specific. Using a \fIVP\fR of "xxx" will list the
available acronyms.
.br
If this option is used with \fI\-\-page=PG\fR and \fIPG\fR is an acronym
then this option is ignored. If \fIPG\fR is a number (e.g. 0xc0) then
\fIVP\fR is used to choose the which vendor specific page (e.g. sharing
page number 0xc0) to decode.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase level of verbosity. When used with \fI\-\-enumerate\fR, in the
list of known log page names, those that have no associated decode logic
are followed by "[hex only]".
.TP
\fB\-V\fR, \fB\-\-version\fR
print out version string then exit.
.SH LOG SELECT
The SCSI LOG SELECT command can be used to reset certain parameters to vendor
specific defaults, save them to non\-volatile storage (i.e. the media), or
supply new page contents. This command has changed between SPC\-3 and SPC\-4
with the addition of the Page and Subpage Code fields which can only be
non zero when the Parameter list length is zero.
.PP
The \fI\-\-select\fR (or \fI\-\-reset\fR) option is required to issue a LOG
SELECT command. If the \fI\-\-in=FN\fR option is not given (or \fIFN\fR is
effectively empty) then the Parameter list length field is set to zero. If
the \fI\-\-in=FN\fR option is is given then its decoded data is placed in
the data\-out buffer and its length in bytes is placed in the Parameter list
length field.
.PP
Other options that are active with the LOG SELECT command are
\fI\-\-control=PC\fR, \fI\-\-reset\fR (which sets the PCR bit) and
\fI\-\-sp\fR.
.SH APPLICATION CLIENT
This is the name of a log page that acts as a container for data provided
by the user. An application client is a SCSI term for the program that issues
commands to a SCSI initiator (often known as a Host Bus Adapter (HBA)). So,
for example, this utility is a SCSI application client.
.PP
The Application Client log page has 64 log parameters with parameters codes
0 to 63. Each can hold 252 bytes of user binary data. That 252 bytes (or
less) of user data, with a 4 byte prefix (for a total of 256 bytes) can be
provided with the \fI\-\-in=FN\fR option. A typical prefix would
be '0,n,83,fc'. The "n" is the parameter code in hex so the last log
parameter would be '0,3f,83,fc'. That log parameter could be read back at
some later time with '\-\-page=0xf \-\-filter=0x<n>'.
.SH INHEX INSTEAD OF DEVICE
This section applies when the \fI\-\-inhex=FN\fR option is used and there
is no \fIDEVICE\fR argument. This can be viewed as a replay facility where
the \fIFN\fR file was created by a prior invocation of this utility, most
likely with the '\-HHHHH' option, with command line output redirection used
to create \fIFN\fR.
.PP
If the \fI\-\-all\fR option is given once then all pages (but not subpages)
found in \fIFN\fR will be decoded, or output in hex if this utility is
unable to decode some of them. If the \fI\-\-all\fR option is given two or
more times then all pages and subpages found in \fIFN\fR will be decoded.
In both cases pages are decoded in the order they are found in \fIFN\fR.
.PP
Next, if the \fI\-\-page=PG\fR] option is given, then \fIFN\fR is searched
for a match on \fIPG\fR and, if found, that log (sub)page is decoded.
If the \fI\-\-list\fR option is given once, then the Supported log pages log
page [0x0,0x0] is decoded, if present. If the \fI\-\-list\fR option is given
two or more times, then the Supported Log Pages and Subpages log
page [0x0,0xff] is decoded, if present.
.PP
If none of the above selection options are given, then this utility will
attempt to decode the first log page found in \fIFN\fR. If there are more
log pages following the first one in \fIFN\fR then they are ignored.
.SH NOTES
This utility will usually do a double fetch of log pages with the SCSI LOG
SENSE command. The first fetch requests a 4 byte response (i.e. place 4 in
the "allocation length" field in the cdb). From that response it can
calculate the actual length of the response which is what it asks for
on the second fetch. This is typical practice in SCSI and guaranteed to
work in the standards. However some older devices don't comply. For
those devices using the \fI\-\-maxlen=LEN\fR option will do a single fetch.
A value of 252 should be a safe starting point.
.PP
Various log pages hold information error rates, device temperature, start
stop cycles since the device was produced and the results of the last
20 self tests. Self tests can be initiated by the sg_senddiag(8) utility.
The smartmontools package provides much of the information found with
sg_logs in a form suitable for monitoring the health of SCSI disks and
tape drives.
.PP
The simplest way to find which log pages can be decoded by this utility is
to use the \fI\-\-enumerate\fR option. Some page names are known but there
is no decode logic; such cases have "[hex only]" after the log page name
when the \fI\-\-verbose\fR option is given with \fI\-\-enumerate\fR.
.PP
Vendors are specifically permitted by the SPC\-6 to _not_ report all pages
and subpages supported by a device. That weakens the usefulness of the pages
that report a list of supported pages and subpages. One guarantee which is
given is that the pages reported shall be in ascending order.
.SH EXIT STATUS
The exit status of sg_logs is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to sg3_utils
version 1.23 . Since then this utility defaults to the newer command line
options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the
first option. See the ENVIRONMENT VARIABLES section for another way to
force the use of these older command line options.
.PP
Options with arguments or with two or more letters can have an extra '\-'
prepended. For example: both '\-pcb' and '\-\-pcb' are acceptable.
.TP
\fB\-a\fR
outputs all the log pages supported by the \fIDEVICE\fR.
Equivalent to \fI\-\-all\fR in the main description.
.TP
\fB\-A\fR
outputs all the log pages and subpages supported by the \fIDEVICE\fR.
Equivalent to \fI\-\-ALL\fR in the main description.
.TP
\fB\-c\fR=\fIPC\fR
Equivalent to \fI\-\-control=PC\fR in the main description.
.TP
\fB\-D\fR=\fIDT\fR
Equivalent to \fI\-\-pdt=DT\fR in the main description.
.TP
\fB\-e\fR
enumerate internal tables to show information about known log pages.
Equivalent to \fI\-\-enumerate\fR in the main description.
.TP
\fB\-E\fR
Equivalent to \fI\-\-exclude\fR in the main description.
.TP
\fB\-h\fR
suppresses decoding of known log sense pages and prints out the
response in hex instead.
.TP
\fB\-i\fR=\fIFN\fR
\fIFN\fR is treated as a file name (or '\-' for stdin) which contains ASCII
hexadecimal representing a log page that will be sent as parameter data of a
LOG SELECT command. See the LOG SELECT section.
.TP
\fB\-H\fR
same action as '\-h' in this section and equivalent to \fI\-\-hex\fR in
the main description.
.TP
\fB\-l\fR
lists the names of all logs sense pages supported by this \fIDEVICE\fR.
Equivalent to \fI\-\-list\fR in the main description.
.TP
\fB\-L\fR
lists the names of all logs sense pages and subpages supported by this
\fIDEVICE\fR. Equivalent to '\-\-list \-\-list' in the main description.
.TP
\fB\-m\fR=\fILEN\fR
request only \fILEN\fR bytes of response data. Default is 0 which is
interpreted as all that is available. \fILEN\fR is decimal unless it has
a leading '0x' or trailing 'h'.  Equivalent to \fI\-\-maxlen=LEN\fR in
the main description.
.TP
\fB\-M\fR=\fIVP\fR
Equivalent to \fI\-\-vendor=VP\fR in the main description.
.TP
\fB\-n\fR
Equivalent to \fI\-\-name\fR in the main description.
.TP
\fB\-N\fR, \fB\-\-new\fR
Switch to the newer style options.
.TP
\fB\-p\fR=\fIPG\fR
log page code to access. \fIPG\fR is either an acronym, a page number, or
a page, subpage pair. Available acronyms can be listed with the
\fI\-\-enumerate\fR option. Page (0 to 3f) and subpage (0 to ff) numbers
are comma separated. The numbers are assumed to be hexadecimal.
.TP
\fB\-paramp\fR=\fIPP\fR
\fIPP\fR is the parameter pointer value (in hex) to place in command.
Should be a number between 0 and ffff inclusive.
.TP
\fB\-pcb\fR
show Parameter Control Byte settings (only relevant when log parameters
being output in ASCII).
.TP
\fB\-ppc\fR
sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e. cleared).
.TP
\fB\-r\fR
use SCSI LOG SELECT command (PCR bit set) to reset the all log pages (or
the given page). Equivalent to \fI\-\-reset\fR in the main description.
.TP
\fB\-R\fR
Equivalent to \fI\-\-readonly\fR in the main description.
.TP
\fB\-select\fR
use a LOG SELECT command. Equivalent to \fI\-\-select\fR in the main
description.
.TP
\fB\-sp\fR
sets the Saving Parameters (SP) bit. Default is 0 (i.e. cleared).
Equivalent to \fI\-\-sp\fR in the main description.
.TP
\fB\-t\fR
outputs the temperature. Equivalent to \fI\-\-temperature\fR in the main
description.
.TP
\fB\-T\fR
outputs the transport ('Protocol specific port') log page. Equivalent
to \fI\-\-transport\fR in the main description.
.TP
\fB\-v\fR
increase level of verbosity.
.TP
\fB\-V\fR
print out version string then exit.
.TP
\fB\-x\fR
suppress the INQUIRY command. Equivalent to \fI\-\-no_inq\fR in the main
description.
.TP
\fB\-?\fR
output usage message then exit.
.SH ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS
can be given. When it is present this utility will expect the older command
line options. So the presence of this environment variable is equivalent to
using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
.SH AUTHOR
Written by Douglas Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2002\-2023 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B smartctl(smartmontools), sg_senddiag(8)
